.\" Copyright 2008-2010 Vadim Zhukov <persgray@gmail.com>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright notice,
.\"    this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright notice,
.\"    this list of conditions and the following disclaimer in the documentation
.\"    and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY AGAVA COMPANY ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
.\" EVENT SHALL THE AGAVA COMPANY OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" The views and conclusions contained in the software and documentation are
.\" those of the authors and should not be interpreted as representing official
.\" policies, either expressed or implied, of the AGAVA Company.
.Dd $Mdocdate$
.Dt RB_RESTORE 1
.Os AGAVA
.Sh NAME
.Nm rb_restore
.Nd operate with backup archives
.Sh SYNOPSIS
.Nm
.Op Fl nOqv
.Op Fl d Ar directory
.Op Fl T Ar mintime
browse\ \&
.Ar profile
.Ar host
.Oo
.Ar module
.Op Ar item
.Oc
.Nm
.Op Fl nOqv
.Op Fl d Ar directory
info\ \ \ \&
.Ar profile
.Ar host
.Ar archive
.Op ...
.Nm
.Op Fl nOqv
.Op Fl d Ar directory
list\ \ \ \&
.Ar profile
.Ar host
.Op Ar option=value ...
.Oo
.Ar modules
.Op Ar item ...
.Oc
.Nm
.Op Fl nOqv
.Op Fl d Ar directory
.Op Fl T Ar mintime
put\ \ \ \ \&
.Ar profile
.Ar host
.Op Ar option=value ...
.Oo
.Ar modules
.Op Ar item ...
.Oc
.Nm
.Op Fl nOqv
.Op Fl d Ar directory
.Op Fl T Ar mintime
restore
.Ar profile
.Ar host
.Op Ar option=value ...
.Oo
.Ar modules
.Op Ar item ...
.Oc
.Sh DESCRIPTION
The
.Nm
utility allows to view information about archives made by
.Xr rb_dump 1 ,
put those archives to clients and restore client data from archives on-the-fly.
.Pp
Being executed,
.Nm
requires
.Ar command :
.\" Cm browse ,
.Cm info ,
.Cm list ,
.Cm show ,
.Cm put
or
.Cm restore .
Those commands are described below, see
.Sx COMMANDS .
.Cm list
and
.Cm show
are synonims.
.Pp
What and how to dump is known from
.Ar profile ,
see
.Xr rb 5 .
Also, one and only one
.Ar host
should be specified, on archvies from which
.Nm
will operate.
.Pp
You can pass additional options to command in the form
.Ar option=value .
Commands accepts different options, which are described altogether commands
themselves.
Global command-line options are descripted below:
.Bl -tag -width Ar
.It Fl d Ar directory
Overrides
.Cm archive_dir
profile option, which specifies directory where backups will reside.
.It Fl n
Enables test mode, useful for debugging purposes.
Produces a lot of output, which isn't needed in normal operation.
.It Fl O
By default,
.Nm
operates on all available archives.
But when
.Fl O
is specified, only archives that were successfully dumped are taken into
account.
In the normal usage case this flag is unneded because automatic rotating
started after each dump cleans up all unsuccessful backup attempts, see
description of
.Va autorotate
option in
.Xr rb 5 .
.It Fl q
Enables quiet mode, with only raw data printed to standard output.
This mode is useful for scripting and makeing wrappers.
.It Fl T Ar mintime
Overrides
.Cm min_remote_time
profile option, which specifies pause made between attempts to connect to a
host.
In opposite to
.Cm min_remote_time ,
.Ar mintime
should be specified in seconds.
Value of 0 disables waiting.
Use with care, because
.Cm min_remote_time
was designed to avoid troubles with firewalls that blocks too
.Dq speedy
clients.
.It Fl v
Enables verbose mode, when
.Nm
will print detailed information what it is doing on stderr.
Same information always goes in log(s), but program output retains some
indentation, while in logs all leading whitespace is stripped.
Overrides
.Fl q
switch.
.El
.Sh COMMANDS
.Bl -tag -width "list, show"
.It browse
Enters interactive mode, where you can explore archive repository for a host
specified.
.It info
Shows detailed information about particular archive(-s).
Accepts any the archive-related file paths in the form
.Dq module/date
or
.Dq module/item/date ,
depending in is
.Va separate_archives
set for the module or not.
Date should be specified in the form YYYYMMDD.
.It list , show
Shows information about existing archives.
If date was not specified, then information about all existing archives for
the client mentioned will be shown.
.It put
Copies archive to a remote host. By default, host entered as
.Ar host
argument is used, but this can be overriden by
.Ar on
option.
Defalut directory to put archive is that one set in
.Va workdir
profile option.
If
.Va workdir
was not set then archive will be put in directory that become current after
connecting to a remote host (usually it is the home directory of user connecting
as).
.It restore
Restores (overwrites) client data on cPanel hosting server where client resides.
.Pp
When restoring files, it'll overwrite any files that have versions in archive,
but do not touch files that were not present in archive.
Be sure to create home directory first, because restoration will be done with
client system user rights, and such user cannot create home directory for
himself.
.Pp
When restoring databases, all tables that have versions in archive will be
overwritten.
Tables that are not mentioned in archive will be left intact.
Be sure to create database first, because clients cannot do this themselves.
.El
.Sh EXAMPLES
View information about archives made for client
.Dq abcru6
which owns domain
.Dq abc.ru :
.Dl $ rb_cpanel show abc.ru abcru6
.Pp
Copy all MySQL database archives for the same client on host
.Dq cp67.agava.net
to his home directory:
.Dl $ rb_cpanel put cp67.agava.net abcru6 mysql
.Pp
The same but shorter:
.Dl $ rb_cpanel put cp67 abcru6 mysql
.Pp
Restore same client's home directory and
.Dq forum
database:
.Dl $ rb_cpanel put cp67 abcru6 files mysql=forum
.Sh SEE ALSO
.Xr rb_restore 1
.Sh AUTHORS
The
.Nm
manual page was written by
.An Vadim Zhukov Aq persgray@gmail.com .
.Sh HISTORY
An
.Nm
utility appeared in
.Nm RB
toolkit 2.1.